Documentation Index
Fetch the complete documentation index at: https://docs.buildbetter.ai/llms.txt
Use this file to discover all available pages before exploring further.
Quick Start
Get your credentials
Find your API key in Settings > API Keys and your Feedback Source ID on your feedback source’s detail page.
Data Attributes
When using the simple script tag, customize basic settings withdata-* attributes:
| Attribute | Default | Description |
|---|---|---|
data-api-key | (required) | Your organization API key |
data-feedback-source-id | (required) | The feedback source to submit to |
data-mode | "floating" | Display mode: floating, popover, inline, or slide-out |
data-position | "bottom-right" | Button position (floating mode): bottom-right, bottom-left, top-right, top-left |
data-button-text | "Feedback" | Text on the trigger button |
data-title | "Send Feedback" | Title at the top of the form |
Programmatic API
For full control, use the JavaScript API. The script exposes a globalBuildBetterFeedback object.
Instance Methods
BuildBetterFeedback.create() returns a widget instance with the following methods:
| Method | Description |
|---|---|
widget.open() | Open the widget (floating, popover, and slide-out modes only) |
widget.close() | Close the widget |
widget.destroy() | Remove the widget from the DOM entirely |
Multiple Instances
You can create multiple widget instances on the same page. Each instance is fully isolated with its own Shadow DOM — styles never leak between widgets or affect your page.Configuration Reference
Your organization API key (
bb_org_...). Found in Settings > API Keys.The ID of the feedback source to submit records to.
Display mode. One of
floating, popover, inline, or slide-out. See Display Modes.Trigger button position (floating mode only). One of
bottom-right, bottom-left, top-right, top-left.Whether the form opens above or below the button (popover mode only). One of
above or below.CSS selector or DOM element reference for inline and popover modes. Required when
mode is inline. Optional for popover — if provided, the button renders inside the container; otherwise it appends to the body.Text displayed on the trigger button (floating, popover, and slide-out modes).
Title displayed at the top of the feedback form.
Array of field configurations. See Field Types. Defaults to a single required textarea.
Pre-fill user identity as hidden context. See User Identity.
Remove the “Powered by BuildBetter” footer from the widget.
Callback fired after a successful submission. Receives an object with
id and fields.Callback fired when a submission fails.
Callback fired when the widget opens.
Callback fired when the widget closes.
Display Modes
- Floating
- Popover
- Inline
- Slide-Out
A floating button fixed to a corner of the viewport. Clicking it opens a feedback card near the button.
Field Types
Configure which fields appear in your feedback form using thefields array. Each field requires a type, name (used as the key when submitting), and label (displayed to the user).
Text
Text
A single-line text input.
Textarea
Textarea
A multi-line text area for longer responses.
Emoji
Emoji
A row of emoji buttons for quick sentiment feedback. The text label (not the emoji character) is submitted as the value, making it easy to filter and analyze.Default emojis: angry, sad, neutral, happy, loveYou can customize the emojis and their labels using
emojiOptions:Star Rating
Star Rating
A 1-5 star selector. Submits the numeric value as a string (e.g.
"4").Select (Dropdown)
Select (Dropdown)
A dropdown with predefined options.
NPS (Net Promoter Score)
NPS (Net Promoter Score)
A 0-10 horizontal scale. Submits the numeric value as a string (e.g.
"8").Field Properties
| Property | Type | Required | Description |
|---|---|---|---|
type | string | Yes | One of: text, textarea, emoji, star-rating, select, nps |
name | string | Yes | Unique key for this field (used in the submitted data) |
label | string | Yes | Label displayed above the field |
required | boolean | No | If true, the field must have a value before submitting |
placeholder | string | No | Placeholder text (text and textarea only) |
options | string[] | No | Dropdown options (select only) |
emojiOptions | EmojiOption[] | No | Custom emoji choices (emoji only). Each item has emoji (the character) and label (the submitted value). |
category | string | No | Override the API field category (advanced) |
Theming
Customize the widget’s appearance to match your brand. The theme applies to all display modes including the inline form background.| Property | Type | Default | Description |
|---|---|---|---|
primaryColor | string | #6366f1 | Accent color for buttons, selections, and highlights |
backgroundColor | string | #ffffff | Background color of the form card |
textColor | string | #1f2937 | Color of labels and body text |
borderRadius | number | 8 | Corner radius in pixels |
fontFamily | string | System font stack | CSS font-family value |
User Identity
If your users are already logged in to your application, you can pass their identity to the widget so feedback is automatically linked to the person in BuildBetter — no need to ask them to fill in their name or email.The
person data is sent as hidden context — it is never displayed in the form. When an email is provided, the widget upserts a person record in BuildBetter and links the feedback submission to them. If the person already exists (matched by email), their record is reused. Name fields are only updated when provided — omitting them won’t overwrite existing data.| Property | Type | Description |
|---|---|---|
email | string | Email address (used to match or create the person) |
firstName | string | First name |
lastName | string | Last name |
Metadata
Pass hidden key-value data with every submission. Metadata fields are never shown in the form — they’re submitted automatically alongside the user’s responses and appear as additional columns in your feedback table. This is useful for capturing page context, app state, or any other information that helps you understand where and when the feedback was given.page_url appears as “Page Url”). All metadata values are stored as strings with category: "metadata".
person vs metadata: Use person for user identity (email, name) — it creates/links a person record in BuildBetter. Use metadata for contextual data about the submission (page URL, plan, app version) — it’s stored as fields on the feedback record itself.Event Callbacks
React to widget lifecycle events with callback functions.Examples
Customer Satisfaction Survey
Customer Satisfaction Survey
A floating NPS survey with optional follow-up, linked to the logged-in user.
Docs Page Feedback (Popover)
Docs Page Feedback (Popover)
A popover button embedded in your documentation pages that captures the current URL automatically.
Feature Request Form (Inline)
Feature Request Form (Inline)
An inline form embedded in your page for collecting detailed feature requests.
Quick Reaction Widget
Quick Reaction Widget
A minimal floating widget with custom emojis for page-level feedback.
Bug Report with Star Rating
Bug Report with Star Rating
A slide-out panel for structured bug reports with severity rating.
Dark Theme Widget
Dark Theme Widget
A fully dark-themed floating widget. The widget uses theme-relative borders so controls stay visible on dark backgrounds.
Widget Builder
Technical Details
Lightweight
~12 KB gzipped. Single JS file, no CSS dependency, no external libraries needed on your page.
Style Isolation
Each widget instance renders inside a Shadow DOM, so its styles never conflict with your page.
Spam Prevention
Built-in 5-second cooldown between submissions. Each submission includes a unique ID for server-side deduplication.
Browser Support
Works in all modern browsers: Chrome, Firefox, Safari, and Edge. See Browser Compatibility for details.
Browser Compatibility
The widget uses Shadow DOM for style isolation, which requires a modern browser. Internet Explorer is not supported.| Browser | Minimum Version | Released |
|---|---|---|
| Chrome | 53+ | 2016 |
| Edge | 79+ | 2020 |
| Firefox | 63+ | 2018 |
| Safari | 10+ | 2016 |
| Safari iOS | 10+ | 2016 |
| Chrome Android | 53+ | 2016 |